textlint による文章校正への対応について【CCG執筆者向け】

textlint による文章校正への対応について【CCG執筆者向け】

Clock Icon2023.08.15

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

このブログについて

本ブログは ナレッジサイトである Classmethod Cloud Guidebook(CCG) 1 の執筆者向けに連携したガイドです。 textlint の活用で一般に参考になる部分もあるため、ブログにて公開しています。

CCGのコンテンツを管理している GitHubリポジトリ上では、 文章校正ツールである textlint を活用しています。

執筆活動で textlint 指摘が出てきた際の、対応ガイドをまとめます。

前提

そもそも textlint とは

textlint は 文章校正ツールです。 Node.js のパッケージとして提供されています。

公開されている様々なルールを適用してカスタマイズ可能です。 例えば、表記ゆれやタイポを検出できます。

DevelopersIOでも解説ブログがあるので、適宜参照ください。

textlint を活用する理由

文章の品質を一定以上に保つ ために活用しています。

CCGは社内の複数エンジニアによる貢献(執筆)で成り立っています。 文章の特性、書きっぷりには個人差があります。 その差異をなるべく抑えるために textlint は役立ちます。

textlint による指摘への対応

CCGでは Pull Request 作成時(および更新時)に textlint による文章校正が走ります。

問題が見つかった際は以下のようなコメントが飛んできます 2

img

この textlint による指摘が無くなるまで、 Pull Request はマージできないようにしています 3

では 指摘が出てきたらどう対応するのか 。 以降で対応策をまとめます。

対応策その1: 文章を改善

第一優先で実施 ください。

指摘された項目を修正して、更新(push) してください。 更新後の 再チェックで指摘が無くなればOKです。

対応策その2: ワードを例外登録

特定のワードを指摘除外にするルール ( textlint-filter-rule-allowlist ) を導入しています。

この除外設定は textlintの設定ファイル (CCGでは .textlintrc.yaml )に記載します。 設定ファイルの allowlist にワードを追記します。

管理者と同意(コミュニケーション)を取った上で 、 同じ Pull Request 内で .textlintrc.yaml を更新して例外登録してください。

以下、例外登録すべき or べきでないの、ざっくりとしたガイドです。

  • 例外登録すべき
    • 正式な専門用語が引っかかる
    • AWSスペルチェックで、部分一致で引っかかる
    • 特殊な記法が引っかかる (例: MkDocs のハイライト記法)
    • その他、特定パターンが引っかかる (※ 正規表現等で厳密に絞れる場合のみ)
  • 例外登録すべきでない
    • 文章の改善・工夫で対応できる場合

対応策その3: コメントアウト

指定した範囲をチェック対象外にするルール ( textlint-filter-rule-comments ) を導入しています。

以下のように textlint-disable 〜 textlint-enable で挟みます。

ここは textlint チェック対象の文章です。

<!-- textlint-disable -->

ここは textlint チェック "対象外" の文章です。

<!-- textlint-enable -->

ここは textlint チェック対象の文章です。

管理者と同意(コミュニケーション)を取った上で 、コメントアウトを適用します。

以下、コメントアウトすべき or べきでないの、ざっくりとしたガイドです。

  • コメントアウトすべき
    • テーブルやコードブロックの表現で引っかかる
    • 例外登録(allowlist) での対応だと大変なもの
  • コメントアウトすべきでない
    • 文章の改善・工夫で対応できる場合
    • 例外登録(allowlist) で効率良く対処できる場合

おわりに

以上、textlint による指摘が出てきた際の対応策でした。

指摘が出ること自体は全然悪いことではないので、 ガンガン執筆していきましょう!

参考


  1. Classmethod Cloud Guidebook(CCG)は クラスメソッドメンバーズ(請求代行サービス)向けに公開している ナレッジサイトです。詳しくは こちらの紹介ブログ を参照ください。 
  2. 実装参考 【GitHub Actions】Markdown 執筆に textlintの自動校正を取り入れる | DevelopersIO 
  3. GitHub Settings の Branch protection rule → Require status checks to pass before merging から設定 

Share this article

facebook logohatena logotwitter logo

© Classmethod, Inc. All rights reserved.